package com.srmt.document.feishu.internal.table;

import com.lark.oapi.service.docx.v1.model.Block;
import com.lark.oapi.service.docx.v1.model.TableMergeInfo;
import com.srmt.document.exception.TableException;
import com.srmt.document.feishu.internal.table.model.TableContext;
import com.srmt.document.model.TableData;

import java.util.Map;

/**
 * 表格读取策略接口
 * 
 * 定义表格内容读取相关的操作，包括单元格内容获取、表格数据转换等。
 * 
 * @author srmt
 * @since 5.0.0
 */
public interface TableReadStrategy extends TableStrategy {
    
    /**
     * 获取单元格内容
     * 
     * @param context 表格上下文
     * @param row 行索引（从1开始）
     * @param col 列索引（从1开始）
     * @return 单元格文本内容
     * @throws TableException 如果获取失败
     */
    String getCellContent(TableContext context, int row, int col) throws TableException;
    
    /**
     * 定位表格中的特定单元格
     * 
     * @param context 表格上下文
     * @param row 行索引（从0开始）
     * @param col 列索引（从0开始）
     * @return 单元格Block ID
     * @throws TableException 如果无法定位单元格
     */
    String locateTableCell(TableContext context, int row, int col) throws TableException;
    
    /**
     * 查找包含指定文本的单元格位置
     * 
     * @param context 表格上下文
     * @param text 要查找的文本
     * @return 单元格位置[row, col]，如果未找到返回null
     * @throws TableException 如果查找失败
     */
    int[] findCellWithText(TableContext context, String text) throws TableException;
    
    /**
     * 获取表格维度信息
     * 
     * @param context 表格上下文
     * @return [行数, 列数]数组
     * @throws TableException 如果获取失败
     */
    int[] getTableDimensions(TableContext context) throws TableException;
    
    /**
     * 获取表格合并信息
     * 
     * @param context 表格上下文
     * @return 合并信息数组，如果没有合并返回null
     * @throws TableException 如果获取失败
     */
    TableMergeInfo[] getTableMergeInfo(TableContext context) throws TableException;
    
    /**
     * 判断指定单元格是否被合并
     * 
     * @param context 表格上下文
     * @param row 行索引
     * @param col 列索引
     * @return 如果被合并返回true
     * @throws TableException 如果判断失败
     */
    boolean isMergedCell(TableContext context, int row, int col) throws TableException;
    
    /**
     * 获取合并单元格的跨度
     * 
     * @param context 表格上下文
     * @param row 行索引
     * @param col 列索引
     * @return [rowSpan, colSpan]数组
     * @throws TableException 如果获取失败
     */
    int[] getCellSpan(TableContext context, int row, int col) throws TableException;
    
    /**
     * 将表格Block转换为TableData对象
     * 
     * @param context 表格上下文
     * @return TableData对象
     * @throws TableException 如果转换失败
     */
    TableData convertToTableData(TableContext context) throws TableException;
    
    /**
     * 从Block构建TableData
     * 
     * @param tableBlock 表格Block
     * @param blockMap Block ID到Block的映射
     * @return TableData对象
     * @throws TableException 如果构建失败
     */
    TableData buildTableFromBlocks(Block tableBlock, Map<String, Block> blockMap) throws TableException;
}